<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Layout Quick Start - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.layout.quickstart.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.layout.quickstart.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.layout.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.layout.html">Zend_Layout</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.layout.options.html">Zend_Layout Configuration Options</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.layout.quickstart" class="section"><div class="info"><h1 class="title">Zend_Layout Quick Start</h1></div>
    

    <p class="para">
        There are two primary use cases for <span class="classname">Zend_Layout</span>: with the
        Zend Framework <acronym class="acronym">MVC</acronym>, and without.
    </p>

    <div class="section" id="zend.layout.quickstart.layouts"><div class="info"><h1 class="title">Layout scripts</h1></div>
        

        <p class="para">
            In both cases, however, you&#039;ll need to create a layout script. Layout scripts simply
            utilize <span class="classname">Zend_View</span> (or whatever view implementation you are
            using). Layout variables are registered with a <span class="classname">Zend_Layout</span> <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" class="link">placeholder</a>,
            and may be accessed via the placeholder helper or by fetching them
            as object properties of the layout object via the layout helper.
        </p>

        <p class="para">
            As an example:
        </p>

        <pre class="programlisting brush: php">
&lt;!DOCTYPE html
    PUBLIC &quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;
    &quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=utf-8&quot; /&gt;
    &lt;title&gt;My Site&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;?php
    // fetch &#039;content&#039; key using layout helper:
    echo $this-&gt;layout()-&gt;content;

    // fetch &#039;foo&#039; key using placeholder helper:
    echo $this-&gt;placeholder(&#039;Zend_Layout&#039;)-&gt;foo;

    // fetch layout object and retrieve various keys from it:
    $layout = $this-&gt;layout();
    echo $layout-&gt;bar;
    echo $layout-&gt;baz;
?&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>


        <p class="para">
            Because <span class="classname">Zend_Layout</span> utilizes <span class="classname">Zend_View</span> for
            rendering, you can also use any view helpers registered, and also
            have access to any previously assigned view variables. Particularly
            useful are the various <a href="zend.view.helpers.html#zend.view.helpers.initial.placeholder" class="link">placeholder
                helpers</a>, as they allow you to
            retrieve content for areas such as the &lt;head&gt; section,
            navigation, etc.:
        </p>

        <pre class="programlisting brush: php">
&lt;!DOCTYPE html
    PUBLIC &quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;
    &quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=utf-8&quot; /&gt;
    &lt;?php echo $this-&gt;headTitle() ?&gt;
    &lt;?php echo $this-&gt;headScript() ?&gt;
    &lt;?php echo $this-&gt;headStyle() ?&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;?php echo $this-&gt;render(&#039;header.phtml&#039;) ?&gt;

    &lt;div id=&quot;nav&quot;&gt;&lt;?php echo $this-&gt;placeholder(&#039;nav&#039;) ?&gt;&lt;/div&gt;

    &lt;div id=&quot;content&quot;&gt;&lt;?php echo $this-&gt;layout()-&gt;content ?&gt;&lt;/div&gt;

    &lt;?php echo $this-&gt;render(&#039;footer.phtml&#039;) ?&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>

    </div>

    <div class="section" id="zend.layout.quickstart.mvc"><div class="info"><h1 class="title">Using Zend_Layout with the Zend Framework MVC</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Controller</span> offers a rich set of functionality for
            extension via its <a href="zend.controller.plugins.html" class="link">front
            controller plugins</a> and <a href="zend.controller.actionhelpers.html" class="link">action controller
            helpers</a>. <span class="classname">Zend_View</span> also has <a href="zend.view.helpers.html" class="link">helpers</a>. <span class="classname">Zend_Layout</span>
            takes advantage of these various extension points when used with the
            <acronym class="acronym">MVC</acronym> components.
        </p>

        <p class="para">
             <span class="methodname">Zend_Layout::startMvc()</span> creates an instance of
            <span class="classname">Zend_Layout</span> with any optional configuration you provide
            it. It then registers a front controller plugin that renders the
            layout with any application content once the dispatch loop is done,
            and registers an action helper to allow access to the layout object
            from your action controllers. Additionally, you may at any time grab
            the layout instance from within a view script using the
            <span class="classname">Layout</span> view helper.
        </p>

        <p class="para">
            First, let&#039;s look at how to initialize <span class="classname">Zend_Layout</span> for use with
            the <acronym class="acronym">MVC</acronym>:
        </p>

        <pre class="programlisting brush: php">
// In your bootstrap:
Zend_Layout::startMvc();
</pre>


        <p class="para">
             <span class="methodname">startMvc()</span> can take an optional array of options or
            <span class="classname">Zend_Config</span> object to customize the instance; these
            options are detailed in <a href="zend.layout.options.html" class="link">this section</a>.
        </p>

        <p class="para">
            In an action controller, you may then access the layout instance as
            an action helper:
        </p>

        <pre class="programlisting brush: php">
class FooController extends Zend_Controller_Action
{
    public function barAction()
    {
        // disable layouts for this action:
        $this-&gt;_helper-&gt;layout-&gt;disableLayout();
    }

    public function bazAction()
    {
        // use different layout script with this action:
        $this-&gt;_helper-&gt;layout-&gt;setLayout(&#039;foobaz&#039;);
    };
}
</pre>


        <p class="para">
            In your view scripts, you can then access the layout object via the
            <span class="classname">Layout</span> view helper. This view helper is slightly
            different than others in that it takes no arguments, and returns an
            object instead of a string value. This allows you to immediately
            call methods on the layout object:
        </p>

        <pre class="programlisting brush: php">
&lt;?php $this-&gt;layout()-&gt;setLayout(&#039;foo&#039;); // set alternate layout ?&gt;
</pre>


        <p class="para">
            At any time, you can fetch the <span class="classname">Zend_Layout</span> instance
            registered with the <acronym class="acronym">MVC</acronym> via the
             <span class="methodname">getMvcInstance()</span> static method:
        </p>

        <pre class="programlisting brush: php">
// Returns null if startMvc() has not first been called
$layout = Zend_Layout::getMvcInstance();
</pre>


        <p class="para">
            Finally, <span class="classname">Zend_Layout</span>&#039;s front controller plugin has one
            important feature in addition to rendering the layout: it retrieves
            all named segments from the response object and assigns them as
            layout variables, assigning the &#039;default&#039; segment to the variable
            &#039;content&#039;. This allows you to access your application content and
            render it in your view scripts.
        </p>

        <p class="para">
            As an example, let&#039;s say your code first hits
             <span class="methodname">FooController::indexAction()</span>, which renders some
            content to the default response segment, and then forwards to
             <span class="methodname">NavController::menuAction()</span>, which renders content to
            the &#039;nav&#039; response segment. Finally, you forward to
             <span class="methodname">CommentController::fetchAction()</span> and fetch some
            comments, but render those to the default response segment as well
            (which appends content to that segment). Your view script could then
            render each separately:
        </p>

        <pre class="programlisting brush: php">
&lt;body&gt;
    &lt;!-- renders /nav/menu --&gt;
    &lt;div id=&quot;nav&quot;&gt;&lt;?php echo $this-&gt;layout()-&gt;nav ?&gt;&lt;/div&gt;

    &lt;!-- renders /foo/index + /comment/fetch --&gt;
    &lt;div id=&quot;content&quot;&gt;&lt;?php echo $this-&gt;layout()-&gt;content ?&gt;&lt;/div&gt;
&lt;/body&gt;
</pre>


        <p class="para">
            This feature is particularly useful when used in conjunction with
            the ActionStack <a href="zend.controller.actionhelpers.html#zend.controller.actionhelpers.actionstack" class="link">action
            helper</a> and <a href="zend.controller.plugins.html#zend.controller.plugins.standard.actionstack" class="link">plugin</a>,
            which you can use to setup a stack of actions through
            which to loop, and thus create widgetized pages.
        </p>
    </div>

    <div class="section" id="zend.layout.quickstart.standalone"><div class="info"><h1 class="title">Using Zend_Layout as a Standalone Component</h1></div>
        

        <p class="para">
            As a standalone component, <span class="classname">Zend_Layout</span> does not offer nearly as
            many features or as much convenience as when used with the <acronym class="acronym">MVC</acronym>.
            However, it still has two chief benefits:
        </p>

        <ul class="itemizedlist">
            <li class="listitem"><p class="para">Scoping of layout variables.</p></li>

            <li class="listitem">
               <p class="para">Isolation of layout view script from other view scripts.</p>
            </li>
        </ul>

        <p class="para">
            When used as a standalone component, simply instantiate the layout
            object, use the various accessors to set state, set variables as
            object properties, and render the layout:
        </p>

        <pre class="programlisting brush: php">
$layout = new Zend_Layout();

// Set a layout script path:
$layout-&gt;setLayoutPath(&#039;/path/to/layouts&#039;);

// set some variables:
$layout-&gt;content = $content;
$layout-&gt;nav     = $nav;

// choose a different layout script:
$layout-&gt;setLayout(&#039;foo&#039;);

// render final layout
echo $layout-&gt;render();
</pre>

    </div>

    <div class="section" id="zend.layout.quickstart.example"><div class="info"><h1 class="title">Sample Layout</h1></div>
        

        <p class="para">
            Sometimes a picture is worth a thousand words. The following is a
            sample layout script showing how it might all come together.
        </p>

         <p class="para">
            <div class="inlinemediaobject"><div class="imageobject"><a href="images/d481d625821a97b9a5eb2cec99dca50e-zend.layout.quickstart.example.png"><img src="images/d481d625821a97b9a5eb2cec99dca50e-zend.layout.quickstart.example.png" alt="zend.layout.quickstart.example.png" width="450" height="583" /></a></div></div>
        </p>

        <p class="para">
            The actual order of elements may vary, depending on the <acronym class="acronym">CSS</acronym> you&#039;ve
            setup; for instance, if you&#039;re using absolute positioning, you may
            be able to have the navigation displayed later in the document, but
            still show up at the top; the same could be said for the sidebar or
            header. The actual mechanics of pulling the content remain the same,
            however.
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.layout.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.layout.html">Zend_Layout</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.layout.options.html">Zend_Layout Configuration Options</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.layout.html">Zend_Layout</a></li>
  <li><a href="zend.layout.introduction.html">Introduction</a></li>
  <li class="active"><a href="zend.layout.quickstart.html">Zend_Layout Quick Start</a></li>
  <li><a href="zend.layout.options.html">Zend_Layout Configuration Options</a></li>
  <li><a href="zend.layout.advanced.html">Zend_Layout Advanced Usage</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>